home *** CD-ROM | disk | FTP | other *** search
Text File | 1992-07-01 | 49.0 KB | 1,541 lines |
- Info file bfd.info, produced by Makeinfo, -*- Text -*- from input
- file ./bfd.texinfo.
-
- START-INFO-DIR-ENTRY
- * Bfd: (bfd). The Binary File Descriptor library.
- END-INFO-DIR-ENTRY
-
- This file documents the BFD library.
-
- Copyright (C) 1991 Free Software Foundation, Inc.
-
- Permission is granted to make and distribute verbatim copies of this
- manual provided the copyright notice and this permission notice are
- preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of this
- manual under the conditions for verbatim copying, subject to the
- terms of the GNU General Public License, which includes the provision
- that the entire resulting derived work is distributed under the terms
- of a permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
- manual into another language, under the above conditions for modified
- versions.
-
-
- File: bfd.info, Node: Top, Next: Overview, Prev: (dir), Up: (dir)
-
- This file documents the binary file descriptor library libbfd.
-
- * Menu:
-
- * Overview:: Overview of BFD
- * BFD front end:: BFD front end
- * BFD back end:: BFD back end
- * Index:: Index
-
-
- File: bfd.info, Node: Overview, Next: BFD front end, Prev: Top, Up: Top
-
- Introduction
- ************
-
- Simply put, BFD is a package which allows applications to use the same
- routines to operate on object files whatever the object file format.
- A different object file format can be supported simply by creating a
- new BFD back end and adding it to the library.
-
- BFD is split into two parts; the front end and the many back ends.
-
- * memory, and various canonical data structures. The front end also
- decides which back end to use, and when to call back end routines.
-
- * end provides a set of calls which the BFD front end can use to
- maintain its canonical form. The back ends also may keep around
- information for their own use, for greater efficiency.
-
- * Menu:
-
- * History:: History
- * How It Works:: How It Works
- * What BFD Version 1 Can Do:: What BFD Version 1 Can Do
-
-
- File: bfd.info, Node: History, Next: How It Works, Prev: Overview, Up: Overview
-
- History
- =======
-
- One spur behind BFD was the desire, on the part of the GNU 960 team at
- Intel Oregon, for interoperability of applications on their COFF and
- b.out file formats. Cygnus was providing GNU support for the team,
- and Cygnus was contracted to provide the required functionality.
-
- The name came from a conversation David Wallace was having with Richard
- Stallman about the library: RMS said that it would be quite
- hard--David said "BFD". Stallman was right, but the name stuck.
-
- At the same time, Ready Systems wanted much the same thing, but for
- different object file formats: IEEE-695, Oasys, Srecords, a.out and
- 68k coff.
-
- BFD was first implemented by members of Cygnus Support; Steve
- Chamberlain (sac@cygnus.com), John Gilmore (gnu@cygnus.com), K.
- Richard Pixley (rich@cygnus.com) and David Henkel-Wallace
- (gumby@cygnus.com).
-
-
- File: bfd.info, Node: How It Works, Next: What BFD Version 1 Can Do, Prev: History, Up: Overview
-
- How It Works
- ============
-
- To use the library, include `bfd.h' and link with `libbfd.a'.
-
- BFD provides a common interface to the parts of an object file for a
- calling application.
-
- When an application sucessfully opens a target file (object, archive or
- whatever) a pointer to an internal structure is returned. This
- pointer points to a structure called `bfd', described in
- `include/bfd.h'. Our convention is to call this pointer a BFD, and
- instances of it within code `abfd'. All operations on the target
- object file are applied as methods to the BFD. The mapping is
- defined within `bfd.h' in a set of macros, all beginning `bfd'_.
-
- For example, this sequence would do what you would probably expect:
- return the number of sections in an object file attached to a BFD
- `abfd'.
-
- #include "bfd.h"
-
- unsigned int number_of_sections(abfd)
- bfd *abfd;
- {
- return bfd_count_sections(abfd);
- }
-
- The abstraction used within BFD is that an object file has a header, a
- number of sections containing raw data, a set of relocations, and
- some symbol information. Also, BFDs opened for archives have the
- additional attribute of an index and contain subordinate BFDs. This
- approach is fine for a.out and coff, but loses efficiency when
- applied to formats such as S-records and IEEE-695.
-
-
- File: bfd.info, Node: What BFD Version 1 Can Do, Prev: How It Works, Up: Overview
-
- What BFD Version 1 Can Do
- =========================
-
- As different information from the the object files is required, BFD
- reads from different sections of the file and processes them. For
- example a very common operation for the linker is processing symbol
- tables. Each BFD back end provides a routine for converting between
- the object file's representation of symbols and an internal canonical
- format. When the linker asks for the symbol table of an object file,
- it calls through the memory pointer to the relevant BFD back end
- routine which reads and converts the table into a canonical form.
- The linker then operates upon the canonical form. When the link is
- finished and the linker writes the output file's symbol table,
- another BFD back end routine is called which takes the newly created
- symbol table and converts it into the chosen output format.
-
- * Menu:
-
- * BFD information loss:: Information Loss
- * Mechanism:: Mechanism
-
-
- File: bfd.info, Node: BFD information loss, Next: Mechanism, Prev: What BFD Version 1 Can Do, Up: What BFD Version 1 Can Do
-
- Information Loss
- ----------------
-
- *Some information is lost due to the nature of the file format.* The
- output targets supported by BFD do not provide identical facilities,
- and information which may be described in one form has nowhere to go
- in another format. One example of this is alignment information in
- `b.out'. There is nowhere in an `a.out' format file to store
- alignment information on the contained data, so when a file is linked
- from `b.out' and an `a.out' image is produced, alignment information
- will not propagate to the output file. (The linker will still use the
- alignment information internally, so the link is performed correctly).
-
- Another example is COFF section names. COFF files may contain an
- unlimited number of sections, each one with a textual section name.
- If the target of the link is a format which does not have many
- sections (eg `a.out') or has sections without names (eg the Oasys
- format) the link cannot be done simply. You can circumvent this
- problem by describing the desired input-to-output section mapping
- with the linker command language.
-
- *Information can be lost during canonicalization.* The BFD internal
- canonical form of the external formats is not exhaustive; there are
- structures in input formats for which there is no direct
- representation internally. This means that the BFD back ends cannot
- maintain all possible data richness through the transformation
- between external to internal and back to external formats.
-
- This limitation is only a problem when an application reads one format
- and writes another. Each BFD back end is responsible for maintaining
- as much data as possible, and the internal BFD canonical form has
- structures which are opaque to the BFD core, and exported only to the
- back ends. When a file is read in one format, the canonical form is
- generated for BFD and the application. At the same time, the back end
- saves away any information which may otherwise be lost. If the data
- is then written back in the same format, the back end routine will be
- able to use the canonical form provided by the BFD core as well as
- the information it prepared earlier. Since there is a great deal of
- commonality between back ends, this mechanism is very useful. There
- is no information lost for this reason when linking or copying big
- endian COFF to little endian COFF, or `a.out' to `b.out'. When a
- mixture of formats is linked, the information is only lost from the
- files whose format differs from the destination.
-
-
- File: bfd.info, Node: Mechanism, Prev: BFD information loss, Up: What BFD Version 1 Can Do
-
- Mechanism
- ---------
-
- The greatest potential for loss of information is when there is least
- overlap between the information provided by the source format, that
- stored by the canonical format, and the information needed by the
- destination format. A brief description of the canonical form may
- help you appreciate what kinds of data you can count on preserving
- across conversions.
-
- *files*
- Information on target machine architecture, particular implementation
- and format type are stored on a per-file basis. Other information
- includes a demand pageable bit and a write protected bit. Note that
- information like Unix magic numbers is not stored here--only the
- magic numbers' meaning, so a `ZMAGIC' file would have both the demand
- pageable bit and the write protected text bit set. The byte order of
- the target is stored on a per-file basis, so that big- and
- little-endian object files may be linked with one another.
-
- *sections*
- Each section in the input file contains the name of the section, the
- original address in the object file, various flags, size and
- alignment information and pointers into other BFD data structures.
-
- *symbols*
- Each symbol contains a pointer to the object file which originally
- defined it, its name, its value, and various flag bits. When a BFD
- back end reads in a symbol table, the back end relocates all symbols
- to make them relative to the base of the section where they were
- defined. This ensures that each symbol points to its containing
- section. Each symbol also has a varying amount of hidden data to
- contain private data for the BFD back end. Since the symbol points
- to the original file, the private data format for that symbol is
- accessible. `gld' can operate on a collection of symbols of wildly
- different formats without problems.
-
- Normal global and simple local symbols are maintained on output, so
- an output file (no matter its format) will retain symbols pointing to
- functions and to global, static, and common variables. Some symbol
- information is not worth retaining; in `a.out' type information is
- stored in the symbol table as long symbol names. This information
- would be useless to most COFF debuggers; the linker has command line
- switches to allow users to throw it away.
-
- There is one word of type information within the symbol, so if the
- format supports symbol type information within symbols (for example
- COFF, IEEE, Oasys) and the type is simple enough to fit within one
- word (nearly everything but aggregates) the information will be
- preserved.
-
- *relocation level*
- Each canonical BFD relocation record contains a pointer to the symbol
- to relocate to, the offset of the data to relocate, the section the
- data is in and a pointer to a relocation type descriptor. Relocation
- is performed effectively by message passing through the relocation
- type descriptor and symbol pointer. It allows relocations to be
- performed on output data using a relocation method only available in
- one of the input formats. For instance, Oasys provides a byte
- relocation format. A relocation record requesting this relocation
- type would point indirectly to a routine to perform this, so the
- relocation may be performed on a byte being written to a COFF file,
- even though 68k COFF has no such relocation type.
-
- *line numbers*
- Object formats can contain, for debugging purposes, some form of
- mapping between symbols, source line numbers, and addresses in the
- output file. These addresses have to be relocated along with the
- symbol information. Each symbol with an associated list of line
- number records points to the first record of the list. The head of a
- line number list consists of a pointer to the symbol, which allows
- divination of the address of the function whose line number is being
- described. The rest of the list is made up of pairs: offsets into the
- section and line numbers. Any format which can simply derive this
- information can pass it successfully between formats (COFF, IEEE and
- Oasys).
-
-
- File: bfd.info, Node: BFD front end, Next: BFD back end, Prev: Overview, Up: Top
-
- BFD front end
- *************
-
- `typedef bfd'
- =============
-
- A BFD is has type `bfd'; objects of this type are the cornerstone of
- any application using `libbfd'. References though the BFD and to data
- in the BFD give the entire BFD functionality. Here is the struct
- used to define the type `bfd'. This contains he major data about the
- file, and contains pointers to the rest of the data.
-
- .
-
- struct _bfd
- {
- /* The filename the application opened the BFD with. */
- CONST char *filename;
-
- /* A pointer to the target jump table. */
- struct bfd_target *xvec;
-
- /* To avoid dragging too many header files into every file that
- includes `<<bfd.h>>', IOSTREAM has been declared as a "char
- *", and MTIME as a "long". Their correct types, to which they
- are cast when used, are "FILE *" and "time_t". The iostream
- is the result of an fopen on the filename. */
- char *iostream;
-
- /* Is the file being cached */
-
- boolean cacheable;
-
- /* Marks whether there was a default target specified when the
- BFD was opened. This is used to select what matching algorithm
- to use to chose the back end. */
-
- boolean target_defaulted;
-
- /* The caching routines use these to maintain a
- least-recently-used list of BFDs */
-
- struct _bfd *lru_prev, *lru_next;
-
- /* When a file is closed by the caching routines, BFD retains
- state information on the file here:
- */
-
- file_ptr where;
-
- /* and here:*/
-
- boolean opened_once;
-
- /* Set if we have a locally maintained mtime value, rather than
- getting it from the file each time: */
-
- boolean mtime_set;
-
- /* File modified time, if mtime_set is true: */
-
- long mtime;
-
- /* Reserved for an unimplemented file locking extension.*/
-
- int ifd;
-
- /* The format which belongs to the BFD.*/
-
- bfd_format format;
-
- /* The direction the BFD was opened with*/
-
- enum bfd_direction {no_direction = 0,
- read_direction = 1,
- write_direction = 2,
- both_direction = 3} direction;
-
- /* Format_specific flags*/
-
- flagword flags;
-
- /* Currently my_archive is tested before adding origin to
- anything. I believe that this can become always an add of
- origin, with origin set to 0 for non archive files. */
-
- file_ptr origin;
-
- /* Remember when output has begun, to stop strange things
- happening. */
- boolean output_has_begun;
-
- /* Pointer to linked list of sections*/
- struct sec *sections;
-
- /* The number of sections */
- unsigned int section_count;
-
- /* Stuff only useful for object files:
- The start address. */
- bfd_vma start_address;
-
- /* Used for input and output*/
- unsigned int symcount;
-
- /* Symbol table for output BFD*/
- struct symbol_cache_entry **outsymbols;
-
- /* Pointer to structure which contains architecture information*/
- struct bfd_arch_info *arch_info;
-
- /* Stuff only useful for archives:*/
- PTR arelt_data;
- struct _bfd *my_archive;
- struct _bfd *next;
- struct _bfd *archive_head;
- boolean has_armap;
-
- /* Used by the back end to hold private data. */
-
- union
- {
- struct aout_data_struct *aout_data;
- struct artdata *aout_ar_data;
- struct _oasys_data *oasys_obj_data;
- struct _oasys_ar_data *oasys_ar_data;
- struct coff_tdata *coff_obj_data;
- struct ieee_data_struct *ieee_data;
- struct ieee_ar_data_struct *ieee_ar_data;
- struct srec_data_struct *srec_data;
- struct elf_obj_tdata_struct *elf_obj_data;
- struct elf_core_tdata_struct *elf_core_data;
- struct bout_data_struct *bout_data;
- struct sun_core_struct *sun_core_data;
- struct trad_core_struct *trad_core_data;
- PTR any;
- } tdata;
-
- /* Used by the application to hold private data*/
- PTR usrdata;
-
- /* Where all the allocated stuff under this BFD goes */
- struct obstack memory;
-
- asymbol **ld_symbols;
- };
-
- `bfd_get_reloc_upper_bound'
- ...........................
-
- *Synopsis*
-
- unsigned int bfd_get_reloc_upper_bound(bfd *abfd, asection *sect);
-
- *Description*
- This function return the number of bytes required to store the relocation
- information associated with section `sect' attached to bfd `abfd'
-
- `bfd_canonicalize_reloc'
- ........................
-
- *Synopsis*
-
- unsigned int bfd_canonicalize_reloc
- (bfd *abfd,
- asection *sec,
- arelent **loc,
- asymbol **syms);
-
- *Description*
- This function calls the back end associated with the open `abfd' and
- translates the external form of the relocation information attached
- to `sec' into the internal canonical form. The table is placed into
- memory at `loc', which has been preallocated, usually by a call to
- `bfd_get_reloc_upper_bound'. The `syms' table is also needed for
- horrible internal magic reasons.
-
- `bfd_set_file_flags'
- ....................
-
- *Synopsis*
-
- boolean bfd_set_file_flags(bfd *abfd, flagword flags);
-
- *Description*
- This function attempts to set the flag word in the referenced BFD
- structure to the value supplied. Possible errors are:
-
- * The flag word contained a bit which was not applicable to the type of
- file. eg, an attempt was made to set the D_PAGED bit on a bfd format
- which does not support demand paging
-
-
- `bfd_set_reloc'
- ................
-
- *Synopsis*
-
- void bfd_set_reloc
- (bfd *abfd, asection *sec, arelent **rel, unsigned int count)
-
- *Description*
- This function sets the relocation pointer and count within a section to
- the supplied values.
-
- `bfd_set_start_address'
- .......................
-
- *Description*
- Marks the entry point of an output BFD.
-
- *Returns*
- Returns `true' on success, `false' otherwise.
-
- *Synopsis*
-
- boolean bfd_set_start_address(bfd *, bfd_vma);
-
- `The bfd_get_mtime function'
- ............................
-
- *Synopsis*
-
- long bfd_get_mtime(bfd *);
-
- *Description*
- Return file modification time (as read from file system, or from archive
- header for archive members).
-
- `stuff'
- .......
-
- *Description*
- stuff which should be documented
-
- #define bfd_sizeof_headers(abfd, reloc) \
- BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, reloc))
-
- #define bfd_find_nearest_line(abfd, sec, syms, off, file, func, line) \
- BFD_SEND (abfd, _bfd_find_nearest_line, (abfd, sec, syms, off, file, func, line))
-
- #define bfd_debug_info_start(abfd) \
- BFD_SEND (abfd, _bfd_debug_info_start, (abfd))
-
- #define bfd_debug_info_end(abfd) \
- BFD_SEND (abfd, _bfd_debug_info_end, (abfd))
-
- #define bfd_debug_info_accumulate(abfd, section) \
- BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section))
-
- #define bfd_stat_arch_elt(abfd, stat) \
- BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat))
-
- #define bfd_coff_swap_aux_in(a,e,t,c,i) \
- BFD_SEND (a, _bfd_coff_swap_aux_in, (a,e,t,c,i))
-
- #define bfd_coff_swap_sym_in(a,e,i) \
- BFD_SEND (a, _bfd_coff_swap_sym_in, (a,e,i))
-
- #define bfd_coff_swap_lineno_in(a,e,i) \
- BFD_SEND ( a, _bfd_coff_swap_lineno_in, (a,e,i))
-
- #define bfd_set_arch_mach(abfd, arch, mach)\
- BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach))
-
- #define bfd_coff_swap_reloc_out(abfd, i, o) \
- BFD_SEND (abfd, _bfd_coff_swap_reloc_out, (abfd, i, o))
-
- #define bfd_coff_swap_lineno_out(abfd, i, o) \
- BFD_SEND (abfd, _bfd_coff_swap_lineno_out, (abfd, i, o))
-
- #define bfd_coff_swap_aux_out(abfd, i, t,c,o) \
- BFD_SEND (abfd, _bfd_coff_swap_aux_out, (abfd, i,t,c, o))
-
- #define bfd_coff_swap_sym_out(abfd, i,o) \
- BFD_SEND (abfd, _bfd_coff_swap_sym_out, (abfd, i, o))
-
- #define bfd_coff_swap_scnhdr_out(abfd, i,o) \
- BFD_SEND (abfd, _bfd_coff_swap_scnhdr_out, (abfd, i, o))
-
- #define bfd_coff_swap_filehdr_out(abfd, i,o) \
- BFD_SEND (abfd, _bfd_coff_swap_filehdr_out, (abfd, i, o))
-
- #define bfd_coff_swap_aouthdr_out(abfd, i,o) \
- BFD_SEND (abfd, _bfd_coff_swap_aouthdr_out, (abfd, i, o))
-
- #define bfd_get_relocated_section_contents(abfd, seclet) \
- BFD_SEND (abfd, _bfd_get_relocated_section_contents, (abfd, seclet))
-
- #define bfd_relax_section(abfd, section, symbols) \
- BFD_SEND (abfd, _bfd_relax_section, (abfd, section, symbols))
-
-
- * Menu:
-
- * Memory Usage::
- * Initialization::
- * Sections::
- * Symbols::
- * Archives::
- * Formats::
- * Relocations::
- * Core Files::
- * Targets::
- * Architectures::
- * Opening and Closing::
- * Constructors::
- * Internal::
- * File Caching::
-
-
- File: bfd.info, Node: Memory Usage, Next: Initialization, Prev: BFD front end, Up: BFD front end
-
- Memory Usage
- ============
-
- BFD keeps all its internal structures in obstacks. There is one obstack
- per open BFD file, into which the current state is stored. When a BFD
- is closed, the obstack is deleted, and so everything which has been
- allocated by libbfd for the closing file will be thrown away.
-
- BFD will not free anything created by an application, but pointers into
- `bfd' structures will be invalidated on a `bfd_close'; for example,
- after a `bfd_close' the vector passed to `bfd_canonicalize_symtab'
- will still be around, since it has been allocated by the application,
- but the data that it pointed to will be lost.
-
- The general rule is not to close a BFD until all operations dependent
- upon data from the BFD have been completed, or all the data from
- within the file has been copied. To help with the management of
- memory, there is a function (`bfd_alloc_size') which returns the
- number of bytes in obstacks associated with the supplied BFD. This
- could be used to select the greediest open BFD, close it to reclaim
- the memory, perform some operation and reopen the BFD again, to get a
- fresh copy of the data structures.
-
-
- File: bfd.info, Node: Initialization, Next: Sections, Prev: Memory Usage, Up: BFD front end
-
- Initialization
- ==============
-
- This is the initialization section
-
- `bfd_init'
- ..........
-
- *Synopsis*
-
- void bfd_init(void);
-
- *Description*
- This routine must be called before any other bfd function to initialize
- magical internal data structures.
-
- `bfd_check_init'
- ................
-
- *Description*
- This routine is called before any other bfd function using initialized
- data is used to ensure that the structures have been initialized.
- Soon this function will go away, and the bfd library will assume that
- bfd_init has been called.
-
- *Synopsis*
-
- void bfd_check_init(void);
-
-
- File: bfd.info, Node: Sections, Next: Symbols, Prev: Initialization, Up: BFD front end
-
- Sections
- ========
-
- Sections are supported in BFD in `section.c'. The raw data contained
- within a BFD is maintained through the section abstraction. A single
- BFD may have any number of sections, and keeps hold of them by
- pointing to the first, each one points to the next in the list.
-
- * Menu:
-
- * Section Input::
- * Section Output::
- * typedef asection::
- * section prototypes::
-
-
-
- File: bfd.info, Node: Section Input, Next: Section Output, Prev: Sections, Up: Sections
-
- Section Input
- -------------
-
- When a BFD is opened for reading, the section structures are created
- and attached to the BFD. Each section has a name which describes the
- section in the outside world - for example, `a.out' would contain at
- least three sections, called `.text', `.data' and `.bss'. Sometimes
- a BFD will contain more than the 'natural' number of sections. A back
- end may attach other sections containing constructor data, or an
- application may add a section (using bfd_make_section) to the
- sections attached to an already open BFD. For example, the linker
- creates a supernumary section `COMMON' for each input file's BFD to
- hold information about common storage. The raw data is not
- necessarily read in at the same time as the section descriptor is
- created. Some targets may leave the data in place until a
- `bfd_get_section_contents' call is made. Other back ends may read in
- all the data at once - For example; an S-record file has to be read
- once to determine the size of the data. An IEEE-695 file doesn't
- contain raw data in sections, but data and relocation expressions
- intermixed, so the data area has to be parsed to get out the data and
- relocations.
-
-
- File: bfd.info, Node: Section Output, Next: typedef asection, Prev: Section Input, Up: Sections
-
- Section Output
- --------------
-
- To write a new object style BFD, the various sections to be written
- have to be created. They are attached to the BFD in the same way as
- input sections, data is written to the sections using
- `bfd_set_section_contents'. The linker uses the fields
- `output_section' and `output_offset' to create an output file. The
- data to be written comes from input sections attached to the output
- sections. The output section structure can be considered a filter
- for the input section, the output section determines the vma of the
- output data and the name, but the input section determines the offset
- into the output section of the data to be written. Eg to create a
- section "O", starting at 0x100, 0x123 long, containing two
- subsections, "A" at offset 0x0 (ie at vma 0x100) and "B" at offset
- 0x20 (ie at vma 0x120) the structures would look like:
-
- section name "A"
- output_offset 0x00
- size 0x20
- output_section -----------> section name "O"
- | vma 0x100
- section name "B" | size 0x123
- output_offset 0x20 |
- size 0x103 |
- output_section --------|
-
-
- Seglets
- --------
-
- The data within a section is stored in a `seglet'. These are much like
- the fixups in `gas'. The seglet abstraction allows the a section to
- grow and shrink within itself. A seglet knows how big it is, and
- which is the next seglet and where the raw data for it is, and also
- points to a list of relocations which apply to it. The seglet is
- used by the linker to perform relaxing on final code. The
- application creates code which is as big as necessary to make it work
- without relaxing, and the user can select whether to relax.
- Sometimes relaxing takes a lot of time. The linker runs around the
- relocations to see if any are attached to data which can be shrunk,
- if so it does it on a seglet by seglet basis.
-
-
- File: bfd.info, Node: typedef asection, Next: section prototypes, Prev: Section Output, Up: Sections
-
- typedef asection
- ----------------
-
- The shape of a section struct:
-
- .
-
- typedef struct sec
- {
- /* The name of the section, the name isn't a copy, the pointer is
- the same as that passed to bfd_make_section. */
-
- CONST char *name;
-
-
- /* Which section is it 0.nth */
-
- int index;
-
- /* The next section in the list belonging to the BFD, or NULL. */
-
- struct sec *next;
-
- /* The field flags contains attributes of the section. Some of
- flags are read in from the object file, and some are
- synthesized from other information. */
-
- flagword flags;
-
- #define SEC_NO_FLAGS 0x000
-
- /* Tells the OS to allocate space for this section when loaded.
- This would clear for a section containing debug information
- only. */
-
-
- #define SEC_ALLOC 0x001
- /* Tells the OS to load the section from the file when loading.
- This would be clear for a .bss section */
-
- #define SEC_LOAD 0x002
- /* The section contains data still to be relocated, so there will
- be some relocation information too. */
-
- #define SEC_RELOC 0x004
-
- /* Obsolete ? */
-
- #define SEC_BALIGN 0x008
-
- /* A signal to the OS that the section contains read only
- data. */
- #define SEC_READONLY 0x010
-
- /* The section contains code only. */
-
- #define SEC_CODE 0x020
-
- /* The section contains data only. */
-
- #define SEC_DATA 0x040
-
- /* The section will reside in ROM. */
-
- #define SEC_ROM 0x080
-
- /* The section contains constructor information. This section
- type is used by the linker to create lists of constructors and
- destructors used by <<g++>>. When a back end sees a symbol
- which should be used in a constructor list, it creates a new
- section for the type of name (eg <<__CTOR_LIST__>>), attaches
- the symbol to it and builds a relocation. To build the lists
- of constructors, all the linker has to to is catenate all the
- sections called <<__CTOR_LIST__>> and relocte the data
- contained within - exactly the operations it would peform on
- standard data. */
-
- #define SEC_CONSTRUCTOR 0x100
-
- /* The section is a constuctor, and should be placed at the
- end of the . */
-
-
- #define SEC_CONSTRUCTOR_TEXT 0x1100
-
- #define SEC_CONSTRUCTOR_DATA 0x2100
-
- #define SEC_CONSTRUCTOR_BSS 0x3100
-
-
- /* The section has contents - a bss section could be
- <<SEC_ALLOC>> | <<SEC_HAS_CONTENTS>>, a debug section could be
- <<SEC_HAS_CONTENTS>> */
-
- #define SEC_HAS_CONTENTS 0x200
-
- /* An instruction to the linker not to output sections
- containing this flag even if they have information which
- would normally be written. */
-
- #define SEC_NEVER_LOAD 0x400
-
-
-
- bfd_vma vma;
-
- /* The size of the section in bytes, as it will be output.
- contains a value even if the section has no contents (eg, the
- size of <<.bss>>). This will be filled in after relocation */
-
- bfd_size_type _cooked_size;
-
- /* The size on disk of the section in bytes originally. Normally this
- value is the same as the size, but if some relaxing has
- been done, then this value will be bigger. */
-
- bfd_size_type _raw_size;
-
- /* If this section is going to be output, then this value is the
- offset into the output section of the first byte in the input
- section. Eg, if this was going to start at the 100th byte in
- the output section, this value would be 100. */
-
- bfd_vma output_offset;
-
- /* The output section through which to map on output. */
-
- struct sec *output_section;
-
- /* The alignment requirement of the section, as an exponent - eg
- 3 aligns to 2^3 (or 8) */
-
- unsigned int alignment_power;
-
- /* If an input section, a pointer to a vector of relocation
- records for the data in this section. */
-
- struct reloc_cache_entry *relocation;
-
- /* If an output section, a pointer to a vector of pointers to
- relocation records for the data in this section. */
-
- struct reloc_cache_entry **orelocation;
-
- /* The number of relocation records in one of the above */
-
- unsigned reloc_count;
-
- /* Information below is back end specific - and not always used
- or updated
-
- File position of section data */
-
- file_ptr filepos;
-
- /* File position of relocation info */
-
- file_ptr rel_filepos;
-
- /* File position of line data */
-
- file_ptr line_filepos;
-
- /* Pointer to data for applications */
-
- PTR userdata;
-
- struct lang_output_section *otheruserdata;
-
- /* Attached line number information */
-
- alent *lineno;
-
- /* Number of line number records */
-
- unsigned int lineno_count;
-
- /* When a section is being output, this value changes as more
- linenumbers are written out */
-
- file_ptr moving_line_filepos;
-
- /* what the section number is in the target world */
-
- int target_index;
-
- PTR used_by_bfd;
-
- /* If this is a constructor section then here is a list of the
- relocations created to relocate items within it. */
-
- struct relent_chain *constructor_chain;
-
- /* The BFD which owns the section. */
-
- bfd *owner;
-
- boolean reloc_done;
- /* A symbol which points at this section only */
- struct symbol_cache_entry *symbol;
- struct symbol_cache_entry **symbol_ptr_ptr;
- struct bfd_seclet_struct *seclets_head;
- struct bfd_seclet_struct *seclets_tail;
- } asection ;
-
-
- #define BFD_ABS_SECTION_NAME "*ABS*"
- #define BFD_UND_SECTION_NAME "*UND*"
- #define BFD_COM_SECTION_NAME "*COM*"
-
- /* the absolute section */
- extern asection bfd_abs_section;
- /* Pointer to the undefined section */
- extern asection bfd_und_section;
- /* Pointer to the common section */
- extern asection bfd_com_section;
-
- extern struct symbol_cache_entry *bfd_abs_symbol;
- extern struct symbol_cache_entry *bfd_com_symbol;
- extern struct symbol_cache_entry *bfd_und_symbol;
- #define bfd_get_section_size_before_reloc(section) \
- (section->reloc_done ? (abort(),1): (section)->_raw_size)
- #define bfd_get_section_size_after_reloc(section) \
- ((section->reloc_done) ? (section)->_cooked_size: (abort(),1))
-
-
- File: bfd.info, Node: section prototypes, Prev: typedef asection, Up: Sections
-
- section prototypes
- ------------------
-
- These are the functions exported by the section handling part of `libbfd'
-
- `bfd_get_section_by_name'
- .........................
-
- *Synopsis*
-
- asection *bfd_get_section_by_name(bfd *abfd, CONST char *name);
-
- *Description*
- Runs through the provided ABFD and returns the `asection' who's name
- matches that provided, otherwise NULL. *Note Sections::, for more
- information.
-
- `bfd_make_section_old_way'
- ..........................
-
- *Synopsis*
-
- asection *bfd_make_section_old_way(bfd *, CONST char *name);
-
- *Description*
- This function creates a new empty section called NAME and attaches it to
- the end of the chain of sections for the BFD supplied. An attempt to
- create a section with a name which is already in use, returns its
- pointer without changing the section chain. It has the funny name
- since this is the way it used to be before is was rewritten...
- Possible errors are:
-
- * If output has already started for this BFD.
-
- * If obstack alloc fails.
-
-
- `bfd_make_section'
- ...................
-
- *Synopsis*
-
- asection * bfd_make_section(bfd *, CONST char *name);
-
- *Description*
- This function creates a new empty section called NAME and attaches it to
- the end of the chain of sections for the BFD supplied. An attempt to
- create a section with a name which is already in use, returns NULL
- without changing the section chain. Possible errors are:
-
- *
-
- `bfd_set_section_flags'
- .......................
-
- *Synopsis*
-
- boolean bfd_set_section_flags(bfd *, asection *, flagword);
-
- *Description*
- Attempts to set the attributes of the section named in the BFD supplied
- to the value. Returns true on success, false on error. Possible error
- returns are:
-
- * The section cannot have one or more of the attributes requested. For
- example, a .bss section in `a.out' may not have the
- `SEC_HAS_CONTENTS' field set.
-
-
- `bfd_map_over_sections'
- ........................
-
- *Synopsis*
-
- void bfd_map_over_sections(bfd *abfd,
- void (*func)(bfd *abfd,
- asection *sect,
- PTR obj),
- PTR obj);
-
- *Description*
- Calls the provided function FUNC for each section attached to the BFD
- ABFD, passing OBJ as an argument. The function will be called as if by
-
- func(abfd, the_section, obj);
-
- This is the prefered method for iterating over sections, an alternative
- would be to use a loop:
-
- section *p;
- for (p = abfd->sections; p != NULL; p = p->next)
- func(abfd, p, ...)
-
-
- `bfd_set_section_size'
- .......................
-
- *Synopsis*
-
- boolean bfd_set_section_size(bfd *, asection *, bfd_size_type val);
-
- *Description*
- Sets SECTION to the size VAL. If the operation is ok, then `true' is
- returned, else `false'. Possible error returns:
-
- * Writing has started to the BFD, so setting the size is invalid
-
-
- `bfd_set_section_contents'
- ...........................
-
- *Synopsis*
-
- boolean bfd_set_section_contents
- (bfd *abfd,
- asection *section,
- PTR data,
- file_ptr offset,
- bfd_size_type count);
-
- *Description*
- Sets the contents of the section SECTION in BFD ABFD to the data starting
- in memory at DATA. The data is written to the output section starting
- at offset OFFSET for COUNT bytes. Normally `true' is returned, else
- `false'. Possible error returns are:
-
- * The output section does not have the `SEC_HAS_CONTENTS' attribute, so
- nothing can be written to it.
-
- * This routine is front end to the back end function
- `_bfd_set_section_contents'.
-
-
- `bfd_get_section_contents'
- ...........................
-
- *Synopsis*
-
- boolean bfd_get_section_contents
- (bfd *abfd, asection *section, PTR location,
- file_ptr offset, bfd_size_type count);
-
- *Description*
- This function reads data from SECTION in BFD ABFD into memory starting at
- LOCATION. The data is read at an offset of OFFSET from the start of
- the input section, and is read for COUNT bytes. If the contents of a
- constuctor with the `SEC_CONSTUCTOR' flag set are requested, then the
- LOCATION is filled with zeroes. If no errors occur, `true' is
- returned, else `false'.
-
-
- File: bfd.info, Node: Symbols, Next: Archives, Prev: Sections, Up: BFD front end
-
- Symbols
- =======
-
- BFD trys to maintain as much symbol information as it can when it moves
- information from file to file. BFD passes information to applications
- though the `asymbol' structure. When the application requests the
- symbol table, BFD reads the table in the native form and translates
- parts of it into the internal format. To maintain more than the
- infomation passed to applications some targets keep some information
- 'behind the sceans', in a structure only the particular back end
- knows about. For example, the coff back end keeps the original symbol
- table structure as well as the canonical structure when a BFD is read
- in. On output, the coff back end can reconstruct the output symbol
- table so that no information is lost, even information unique to coff
- which BFD doesn't know or understand. If a coff symbol table was
- read, but was written through an a.out back end, all the coff
- specific information would be lost. The symbol table of a BFD is not
- necessarily read in until a canonicalize request is made. Then the
- BFD back end fills in a table provided by the application with
- pointers to the canonical information. To output symbols, the
- application provides BFD with a table of pointers to pointers to
- `asymbol's. This allows applications like the linker to output a
- symbol as read, since the 'behind the sceens' information will be
- still available.
-
- * Menu:
-
- * Reading Symbols::
- * Writing Symbols::
- * typedef asymbol::
- * symbol handling functions::
-
-
-
- File: bfd.info, Node: Reading Symbols, Next: Writing Symbols, Prev: Symbols, Up: Symbols
-
- Reading Symbols
- ---------------
-
- There are two stages to reading a symbol table from a BFD; allocating
- storage, and the actual reading process. This is an excerpt from an
- appliction which reads the symbol table:
-
- unsigned int storage_needed;
- asymbol **symbol_table;
- unsigned int number_of_symbols;
- unsigned int i;
-
- storage_needed = get_symtab_upper_bound (abfd);
-
- if (storage_needed == 0) {
- return ;
- }
- symbol_table = (asymbol **) bfd_xmalloc (storage_needed);
- ...
- number_of_symbols =
- bfd_canonicalize_symtab (abfd, symbol_table);
-
- for (i = 0; i < number_of_symbols; i++) {
- process_symbol (symbol_table[i]);
- }
-
- All storage for the symbols themselves is in an obstack connected to
- the BFD, and is freed when the BFD is closed.
-
-
- File: bfd.info, Node: Writing Symbols, Next: typedef asymbol, Prev: Reading Symbols, Up: Symbols
-
- Writing Symbols
- ---------------
-
- Writing of a symbol table is automatic when a BFD open for writing is
- closed. The application attaches a vector of pointers to pointers to
- symbols to the BFD being written, and fills in the symbol count. The
- close and cleanup code reads through the table provided and performs
- all the necessary operations. The outputing code must always be
- provided with an 'owned' symbol; one which has come from another BFD,
- or one which has been created using `bfd_make_empty_symbol'. An
- example showing the creation of a symbol table with only one element:
-
- #include "bfd.h"
- main()
- {
- bfd *abfd;
- asymbol *ptrs[2];
- asymbol *new;
-
- abfd = bfd_openw("foo","a.out-sunos-big");
- bfd_set_format(abfd, bfd_object);
- new = bfd_make_empty_symbol(abfd);
- new->name = "dummy_symbol";
- new->section = bfd_make_section_old_way(abfd, ".text");
- new->flags = BSF_GLOBAL;
- new->value = 0x12345;
-
- ptrs[0] = new;
- ptrs[1] = (asymbol *)0;
-
- bfd_set_symtab(abfd, ptrs, 1);
- bfd_close(abfd);
- }
-
- ./makesym
- nm foo
- 00012345 A dummy_symbol
-
- Many formats cannot represent arbitary symbol information; for instance
- the `a.out' object format does not allow an arbitary number of
- sections. A symbol pointing to a section which is not one of
- `.text', `.data' or `.bss' cannot be described.
-
-
- File: bfd.info, Node: typedef asymbol, Next: symbol handling functions, Prev: Writing Symbols, Up: Symbols
-
- typedef asymbol
- ---------------
-
- An `asymbol' has the form:
-
- .typedef struct symbol_cache_entry
-
- {
- /* A pointer to the BFD which owns the symbol. This information
- is necessary so that a back end can work out what additional
- (invisible to the application writer) information is carried
- with the symbol. */
-
- struct _bfd *the_bfd;
-
- /* The text of the symbol. The name is left alone, and not copied - the
- application may not alter it. */
- CONST char *name;
-
- /* The value of the symbol.*/
- symvalue value;
-
- /* Attributes of a symbol: */
-
- #define BSF_NO_FLAGS 0x00
-
- /* The symbol has local scope; <<static>> in <<C>>. The value
- is the offset into the section of the data. */
- #define BSF_LOCAL 0x01
-
- /* The symbol has global scope; initialized data in <<C>>. The
- value is the offset into the section of the data. */
- #define BSF_GLOBAL 0x02
-
- /* Obsolete */
- #define BSF_IMPORT 0x04
-
- /* The symbol has global scope, and is exported. The value is
- the offset into the section of the data. */
- #define BSF_EXPORT 0x08
-
- /* The symbol is undefined. <<extern>> in <<C>>. The value has
- no meaning. */
- #define BSF_UNDEFINED_OBS 0x10
-
- /* The symbol is common, initialized to zero; default in
- <<C>>. The value is the size of the object in bytes. */
- #define BSF_FORT_COMM_OBS 0x20
-
- /* A normal C symbol would be one of:
- <<BSF_LOCAL>>, <<BSF_FORT_COMM>>, <<BSF_UNDEFINED>> or
- <<BSF_EXPORT|BSD_GLOBAL>> */
-
- /* The symbol is a debugging record. The value has an arbitary
- meaning. */
- #define BSF_DEBUGGING 0x40
-
- /* Used by the linker */
- #define BSF_KEEP 0x10000
- #define BSF_KEEP_G 0x80000
-
- /* Unused */
- #define BSF_WEAK 0x100000
- #define BSF_CTOR 0x200000
-
- /* This symbol was created to point to a section */
- #define BSF_SECTION_SYM 0x400000
-
- /* The symbol used to be a common symbol, but now it is
- allocated. */
- #define BSF_OLD_COMMON 0x800000
-
- /* The default value for common data. */
- #define BFD_FORT_COMM_DEFAULT_VALUE 0
-
- /* In some files the type of a symbol sometimes alters its
- location in an output file - ie in coff a <<ISFCN>> symbol
- which is also <<C_EXT>> symbol appears where it was
- declared and not at the end of a section. This bit is set
- by the target BFD part to convey this information. */
-
- #define BSF_NOT_AT_END 0x40000
-
- /* Signal that the symbol is the label of constructor section. */
- #define BSF_CONSTRUCTOR 0x1000000
-
- /* Signal that the symbol is a warning symbol. If the symbol
- is a warning symbol, then the value field (I know this is
- tacky) will point to the asymbol which when referenced will
- cause the warning. */
- #define BSF_WARNING 0x2000000
-
- /* Signal that the symbol is indirect. The value of the symbol
- is a pointer to an undefined asymbol which contains the
- name to use instead. */
- #define BSF_INDIRECT 0x4000000
-
- flagword flags;
-
- /* A pointer to the section to which this symbol is
- relative. This will always be non NULL, there are special
- sections for undefined and absolute symbols */
- struct sec *section;
-
- /* Back end special data. This is being phased out in favour
- of making this a union. */
- PTR udata;
-
- } asymbol;
-
-
- File: bfd.info, Node: symbol handling functions, Prev: typedef asymbol, Up: Symbols
-
- Symbol Handling Functions
- -------------------------
-
-
- `get_symtab_upper_bound'
- .........................
-
- *Description*
- Returns the number of bytes required in a vector of pointers to
- `asymbols' for all the symbols in the supplied BFD, including a
- terminal NULL pointer. If there are no symbols in the BFD, then 0 is
- returned.
-
- #define get_symtab_upper_bound(abfd) \
- BFD_SEND (abfd, _get_symtab_upper_bound, (abfd))
-
-
- `bfd_canonicalize_symtab'
- ..........................
-
- *Description*
- Supplied a BFD and a pointer to an uninitialized vector of pointers. This
- reads in the symbols from the BFD, and fills in the table with
- pointers to the symbols, and a trailing NULL. The routine returns
- the actual number of symbol pointers not including the NULL.
-
- #define bfd_canonicalize_symtab(abfd, location) \
- BFD_SEND (abfd, _bfd_canonicalize_symtab,\
- (abfd, location))
-
-
- `bfd_set_symtab'
- .................
-
- *Description*
- Provided a table of pointers to symbols and a count, writes to the output
- BFD the symbols when closed.
-
- *Synopsis*
-
- boolean bfd_set_symtab (bfd *, asymbol **, unsigned int );
-
- `bfd_print_symbol_vandf'
- ........................
-
- *Description*
- Prints the value and flags of the symbol supplied to the stream file.
-
- *Synopsis*
-
- void bfd_print_symbol_vandf(PTR file, asymbol *symbol);
-
- `bfd_make_empty_symbol'
- .......................
-
- *Description*
- This function creates a new `asymbol' structure for the BFD, and returns
- a pointer to it. This routine is necessary, since each back end has
- private information surrounding the `asymbol'. Building your own
- `asymbol' and pointing to it will not create the private information,
- and will cause problems later on.
-
- #define bfd_make_empty_symbol(abfd) \
- BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd))
-
-
- `bfd_decode_symclass'
- ......................
-
- *Description*
- Return a lower-case character corresponding to the symbol class of symbol.
-
- *Synopsis*
-
- int bfd_decode_symclass(asymbol *symbol);
-
-
- File: bfd.info, Node: Archives, Next: Formats, Prev: Symbols, Up: BFD front end
-
- Archives
- ========
-
-
- *Description*
- Archives are supported in BFD in `archive.c'. An archive (or library) is
- just another BFD. It has a symbol table, although there's not much a
- user program will do with it. The big difference between an archive
- BFD and an ordinary BFD is that the archive doesn't have sections.
- Instead it has a chain of BFDs considered its contents. These BFDs
- can be manipulated just like any other. The BFDs contained in an
- archive opened for reading will all be opened for reading; you may
- put either input or output BFDs into an archive opened for output; it
- will be handled correctly when the archive is closed. Use
- `bfd_openr_next_archived_file' to step through all the contents of an
- archive opened for input. It's not required that you read the entire
- archive if you don't want to! Read it until you find what you want.
- Archive contents of output BFDs are chained through the `next'
- pointer in a BFD. The first one is findable through the
- `archive_head' slot of the archive. Set it with `set_archive_head'
- (q.v.). A given BFD may be in only one open output archive at a time.
- As expected, the BFD archive code is more general than the archive
- code of any given environment. BFD archives may contain files of
- different formats (eg a.out and coff) and even different
- architectures. You may even place archives recursively into archives!
- This can cause unexpected confusion, since some archive formats are
- more expressive than others. For instance intel COFF archives can
- preserve long filenames; Sun a.out archives cannot. If you move a
- file from the first to the second format and back again, the filename
- may be truncated. Likewise, different a.out environments have
- different conventions as to how they truncate filenames, whether they
- preserve directory names in filenames, etc. When interoperating with
- native tools, be sure your files are homogeneous. Beware: most of
- these formats do not react well to the presence of spaces in
- filenames. We do the best we can, but can't always handle this due
- to restrctions in the format of archives. Many unix utilities are
- braindead in regards to spaces and such in filenames anyway, so this
- shouldn't be much of a restriction.
-
- `bfd_get_next_mapent'
- .....................
-
- *Synopsis*
-
- symindex bfd_get_next_mapent(bfd *, symindex previous, carsym ** sym);
-
- *Description*
- This function steps through an archive's symbol table (if it has one).
- Successively updates `sym' with the next symbol's information,
- returning that symbol's (internal) index into the symbol table.
- Supply BFD_NO_MORE_SYMBOLS as the `previous' entry to get the first
- one; returns BFD_NO_MORE_SYMBOLS when you're already got the last one.
- A `carsym' is a canonical archive symbol. The only user-visible
- element is its name, a null-terminated string.
-
- `bfd_set_archive_head'
- ......................
-
- *Synopsis*
-
- boolean bfd_set_archive_head(bfd *output, bfd *new_head);
-
- *Description*
- Used whilst processing archives. Sets the head of the chain of BFDs
- contained in an archive to NEW_HEAD.
-
- `bfd_get_elt_at_index'
- ......................
-
- *Synopsis*
-
- bfd *bfd_get_elt_at_index(bfd * archive, int index);
-
- *Description*
- Return the bfd which is referenced by the symbol indexed by `index'.
- `index' should have been returned by `bfd_get_next_mapent' (q.v.).
-
- `bfd_openr_next_archived_file'
- ..............................
-
- *Synopsis*
-
- bfd* bfd_openr_next_archived_file(bfd *archive, bfd *previous);
-
- *Description*
- Initially provided a BFD containing an archive and NULL, opens an inpout
- BFD on the first contained element and returns that. Subsequent
- calls to bfd_openr_next_archived_file should pass the archive and the
- previous return value to return a created BFD to the next contained
- element. NULL is returned when there are no more.
-
-
-